home *** CD-ROM | disk | FTP | other *** search
/ A.C.E. 2 / ACE CD 2.iso / FILES / UTILS / AMOSPRO5.DMS / in.adf / Equates / Equates.Doc < prev    next >
Encoding:
Text File  |  1993-03-10  |  10.6 KB  |  312 lines
  1. #HYP2000
  2.                {[000,4,7]                                       }
  3.                {[000,4,7]    AMOS Professional System Equate    }
  4.                {[000,4,7]                                       }
  5.  
  6.  
  7. Welcome  to  the AMOS Pro System Equates!  This powerfull system enable you
  8. to directly access all Amiga Equates, in a symbolic manner.  AMOS Pro allow
  9. you to have a clean, system friendly access to the ROM's library.
  10.  
  11. Please select an option:
  12.  
  13.                {[32 ,6,3]           How does it work?           }
  14.                {[90 ,6,3]      Which equates are included?      }
  15.                {[140,6,3]      How to add your own equates.     }
  16.  
  17.                {[ADD,4,7]  RUN and add equates to current file  }
  18.                {[CRE,4,7]  RUN and create a new equate file     }
  19.  
  20.                {[QUT,4,7]                  Quit                 }
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.                {[000,4,7]                                       }
  33.                {[000,4,7]           How does it work?           }
  34.                {[000,4,7]                                       }
  35.  
  36.  
  37. AMOS  Pro  offers  four new instructions to deal with the equates (for more
  38. information, please refer to the AMOS Pro User Guide).
  39.  
  40.     =Equ("The_Equate")
  41.     =Lvo("System_Function")
  42.     =Struc(Address,"Position")=
  43.     =Struc$(Address,"Position")=
  44.  
  45. If during testing time AMOS Pro encounters one of the above instructions it
  46. will load the following file into memory:
  47.  
  48.     "AMOSPro_Tutorial:AMOSPro_System_Equates"
  49.  
  50. AMOS  Pro  explores  it,  looking  for  the specified equate value.  If the
  51. equate is found, its value is poked directly into the AMOS source code.  It
  52. remains  there  until  you  change the line with the editor.  Next time you
  53. test  the  program,  AMOS  Pro  will simply verify that the equate has been
  54. defined and skip the instruction.
  55.  
  56. This means that once the program has been tested, AMOS Pro will not need to
  57. load the Equate file (unless you change the source again).  This allows you
  58. to  send  programs  which  contain  Equates  that someone else doesn't have
  59. access  too.   Or  to  someone who doesn't even have the equates file!  For
  60. safe  keeping,  it's  a  good  idea to place the =Equ("") instructions into
  61. closed procedures, ensuring they won't be changed by mistake.
  62.  
  63. The  Equate  file remains in memory wherever possible.  As long as a memory
  64. flush  does  not  occur.   So if you have enough RAM it will only be loaded
  65. once.   Floppy  disc  users  will  have to keep inserting the disc with the
  66. equates  file  on  if they don't have enough RAM.  (If you're serious about
  67. developing  you must have plenty of RAM and a hard disc).  Close Editor and
  68. Kill  Editor  are  the  only instructions which will erase the Equate file.
  69. (If  they  are enabled within your configuration file.) This ensures enough
  70. RAM is freed when needed.
  71.  
  72. ATTENTION:   Set  Equate Bank is no longer used.  We have realised that the
  73. above  method was much better.  It saves using a bank for storage.  To keep
  74. AMOS  Pro's  compatible,  it  is necessary to leave this command within the
  75. instruction set.  But it has absolutely NO EFFECT!
  76.  
  77.  
  78.                {[001,4,3]             Back to Menu              }
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.                {[000,4,7]                                       }
  92.                {[000,4,7]      Which equates are included?      }
  93.                {[000,4,7]                                       }
  94.  
  95.  
  96. The  Amiga  system  has  a  LOT of equates.  Inserting all of them into the
  97. equate file would have made it as big as 400k!
  98.  
  99. Here is the list of files included in this file:
  100.  
  101.     All: dos.library, exec.library, math(s).library,
  102.         icon.library _LVOs,
  103.     "exec/exec.i"
  104.     "dos/dos.i"
  105.     "dos/dosextens.i"
  106.     "libraries/locale.i"
  107.  
  108.     "devices/audio.i"
  109.     "devices/bootblock.i"
  110.     "devices/clipboard.i"
  111.     "devices/gameport.i"
  112.     "devices/parallel.i"
  113.     "devices/printer.i"
  114.     "devices/prtbase.i"
  115.     "devices/prtgfx.i"
  116.     "devices/scsidisk.i"
  117.     "devices/serial.i"
  118.     "devices/timer.i"
  119.     "devices/trackdisk.i"
  120.     "hardware/Custom.i"
  121.     "rexx/errors.i"
  122.     "rexx/rexxio.i"
  123.     "rexx/rxslib.i"
  124.     "rexx/storage.i"
  125.  
  126. This means you have total control over dos and exec, any devices, arexx and
  127. the  hardware  chipset.   If  you  can't find the equates you need for your
  128. applications then read the next chapter.
  129.  
  130.                {[001,4,3]             Back to Menu              }
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.                {[000,4,7]                                       }
  143.                {[000,4,7]     How to add your own equate.       }
  144.                {[000,4,7]                                       }
  145.  
  146.  
  147. There  are two methods to achieve this task and it depends on the number of
  148. equates you want to add.
  149.  
  150.  
  151. 1. Simple method - using a text editor
  152. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  153. The  equate  file  is  a plain ASCII file. Just load it into your favourite
  154. text  editor.   You  will see immediately that the structure of the file is
  155. very simple:
  156.  
  157.     The_Equate:$XXXXXXXX,Type
  158.  
  159. * The_Equate is the name of the equate to be defined.  Beware!  Case is
  160.   important.  A colon must lie right at the end of name (no spaces).
  161.  
  162. * $XXXXXXXX is the value of this equate.  It can be hexadecimal, decimal,
  163.   or binary (with a %).
  164.  
  165. * Type defines the type of the equate:
  166.  
  167.     0 Byte
  168.     1 Word, Bool
  169.     2 Long
  170.     3 UByte
  171.     4 UWord
  172.     5 ULong
  173.     6 APTR, FPRT, CPRR
  174.     7 No special type.
  175.  
  176. The =Equ("") function returns any kind of equate, regardless of its kind.
  177.  
  178. The  =Lvo("")  function also returns any kind of equates, but add an "_LVO"
  179. to the name of the specified equate before looking for it in the file.
  180.  
  181. =STRUC= only works with equates of type 0 to 6
  182.  
  183. =STRUC$= only works with equates of type 6
  184.  
  185. How to add your new equate:
  186.  
  187. * Go to the bottom of the file.
  188. * Type in your equate, no spaces and respecting the types (choose type 7 if
  189.   you do not know).
  190. * Continue for every other equate you're adding.
  191. * Save your file.
  192.  
  193.  
  194. 2. Using Make_Equate.AMOS.
  195. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  196. This program automatically converts a listing produced by an assembler into
  197. a  file  which  AMOS Pro will understand.  Make_Equates was used to produce
  198. the "AMOSPro_System_Equate" file on you master disc.
  199.  
  200. How to proceed?
  201.  
  202. * You should use Genam2 (or 3), in fact the assembler, Genim2.
  203.  
  204. * You must create a source listing which includes all the files you want to
  205.   grab the equates from.  Here is the source used for the default equate
  206.   file:
  207.  
  208.  
  209. ; Make sure all macros are listed
  210.         OPT M+
  211.  
  212. ; My own include directory,
  213.         IncDir  "Work:includes/i/"    
  214.  
  215. ; Let's go with the includes
  216.         Include "exec/exec.i"
  217.         Include "dos/dos.i"
  218.         Include "dos/dosextens.i"
  219.         Include "libraries/locale.i"
  220.  
  221.         Include "devices/audio.i"
  222.         Include "devices/bootblock.i"
  223.         Include "devices/clipboard.i"
  224.         Include "devices/gameport.i"
  225.         Include "devices/parallel.i"
  226.         Include "devices/printer.i"
  227.         Include "devices/prtbase.i"
  228.         Include "devices/prtgfx.i"
  229.         Include "devices/scsidisk.i"
  230.         Include "devices/serial.i"
  231.         Include "devices/timer.i"
  232.         Include "devices/trackdisk.i"
  233.         Include "hardware/Custom.i"
  234.         Include "rexx/errors.i"
  235.         Include "rexx/rexxio.i"
  236.         Include "rexx/rxslib.i"
  237.         Include "rexx/storage.i"
  238.  
  239. * Under a CLI, you must assemble the source, with the "-p" option, this
  240.   informs the assembler to produce a 2 pass assembly listing.  Here is an
  241.   example of the listing produced for the default file:
  242.  
  243.    22 00.00000000                      * unit defintions
  244.    23   =00000000                      UNIT_MICROHZ    EQU     0
  245.    24   =00000001                      UNIT_VBLANK     EQU     1
  246.    25   =00000002                      UNIT_ECLOCK     EQU     2
  247.    26   =00000003                      UNIT_WAITUNTIL  EQU     3
  248.    27   =00000004                      UNIT_WAITECLOCK EQU     4
  249.    28 00.00000000                      
  250.    29 00.00000000                      TIMERNAME       MACRO
  251.    30 00.00000000                                      DC.B    'timer.device',0
  252.    31 00.00000000                                      DS.W    0
  253.    32 00.00000000                                      ENDM
  254.    33 00.00000000                      
  255.    34 00.00000000                       STRUCTURE TIMEVAL,0
  256.    34   =00000000+                     TIMEVAL     EQU     0
  257.    34   =00000000+                     SOFFSET     SET     0
  258.    34 00.00000000                                  ENDM
  259.    35 00.00000000                              ULONG   TV_SECS
  260.    35   =00000000+                     TV_SECS     EQU     SOFFSET
  261.    35   =00000004+                     SOFFSET     SET     SOFFSET+4
  262.    35 00.00000000                                  ENDM
  263.    36 00.00000000                              ULONG   TV_MICRO
  264.    36   =00000004+                     TV_MICRO            EQU     SOFFSET
  265.    36   =00000008+                     SOFFSET     SET     SOFFSET+4
  266.    36 00.00000000                                  ENDM
  267.    37 00.00000000                              LABEL   TV_SIZE
  268.    37   =00000008+                     TV_SIZE     EQU     SOFFSET
  269.    37 00.00000000                                  ENDM
  270.    38 00.00000000                      
  271.    39 00.00000000                       STRUCTURE ECLOCKVAL,0
  272.    39   =00000000+                     ECLOCKVAL           EQU     0
  273.    39   =00000000+                     SOFFSET     SET     0
  274.    39 00.00000000                                  ENDM
  275.    40 00.00000000                              ULONG   EV_HI
  276.    40   =00000000+                     EV_HI       EQU     SOFFSET
  277.    40   =00000004+                     SOFFSET     SET     SOFFSET+4
  278.    40 00.00000000                                  ENDM
  279.    41 00.00000000                              ULONG   EV_LO
  280.    41   =00000004+                     EV_LO       EQU     SOFFSET
  281.    41   =00000008+                     SOFFSET     SET     SOFFSET+4
  282.    41 00.00000000                                  ENDM
  283.    42 00.00000000                              LABEL   EV_SIZE
  284.    42   =00000008+                     EV_SIZE     EQU     SOFFSET
  285.    42 00.00000000                                  ENDM
  286.    43 00.00000000                      
  287.  
  288.   No need to tell you that this can can be enormous (the default one is
  289.   600k!).  I suggest you work on a hard-drive!
  290.  
  291. * Once the .LST file is created, you run Make_Equates.AMOS.  The program
  292.   will explore the .LST file, line by line, and take any labels out of it.
  293.   It automatically detects the type of the label from the listing,
  294.   and creates the proper line for AMOS Pro.
  295.  
  296.   For security reasons the program works on a temporary file on the
  297.   Ram Disc (you can set the path of the temporary file at the beginning of
  298.   the program).  When everything is finished you have the option of
  299.   copying the new file over the old one.
  300.  
  301.   You can either:
  302.  
  303.         a) Create a new file
  304.         b) Add labels to the existing file.
  305.  
  306.   In both cases, any label defined twice will not be added to the file.  At
  307.   the  end  of  the  process  the  number  of  new and duplicated labels is
  308.   reported.
  309.  
  310.  
  311.                {[001,4,3]             Back to Menu              }
  312.